\chapter{QMap}

template <typename Key, typename T> class QMap

QMap 类是一种模板类，提供基于红黑树的字典类结构。更多内容...


\begin{tabular}{|r|l|}
	\hline
	属性 & 方法 \\
	\hline
	头文件 & \#include <QMap>\\      
	\hline
	qmake & QT += core\\      
	\hline
	派生类:	& QMultiMap \\
	\hline
\end{tabular}

\begin{compactitem}
\item 所有成员列表，包括继承的成员
\item 废弃的成员
\end{compactitem}

\begin{notice}
该类中的所有函数都是可重入的。
\end{notice}

\section{公共成员类型}

\begin{longtable}[l]{|r|l|}
\hline
class	& const\_iterator \\
\hline
class &	iterator \\ 
\hline
class &	key\_iterator \\ 
\hline
typedef	&ConstIterator \\ 
\hline
typedef	&Iterator \\ 
\hline
typedef	&const\_key\_value\_iterator \\
\hline
typedef	&difference\_type \\        
\hline
typedef	&key\_type \\
\hline
typedef & key\_value\_iterator \\
\hline
typedef	&mapped\_type \\ 
\hline
typedef	&size\_type \\ 
\hline
\end{longtable}

\section{公共成员函数}

\begin{longtable}[l]{|r|m{22em}|}
\hline
& QMap(const typename std::map<Key, T> \&other) \\
\hline
&QMap(QMap<Key, T> \&\&other)\\
\hline
& QMap(const QMap<Key, T> \&other)\\
\hline
& QMap(std::initializer\_list<std::pair<Key, T>> list)\\
\hline
& Map()\\
\hline
QMap<Key, T> &	operator=(QMap<Key, T> \&\&other) \\
\hline 
QMap<Key, T> &	operator=(const QMap<Key, T> \&other)\\ 
\hline
& $\sim$QMap() \\
\hline
QMap::iterator &	begin() \\ 
\hline
QMap::const\_iterator	&begin() const \\
\hline
QMap::const\_iterator&	cbegin() const \\
\hline
QMap::const\_iterator &	cend() const \\ 
\hline
void	& clear() \\ 
\hline
QMap::const\_iterator &	constBegin() const \\ 
\hline
QMap::const\_iterator &	constEnd() const \\
\hline
QMap::const\_iterator&	constFind(const Key \&key) const \\
\hline
QMap::const\_key\_value\_iterator&	constKeyValueBegin() const \\
\hline
QMap::const\_key\_value\_iterator&	constKeyValueEnd() const \\
\hline
bool &	contains(const Key \&key) const \\
\hline
int	&count(const Key \&key) const \\
\hline
int	&count() const \\ 
\hline
bool&	empty() const \\
\hline
QMap::iterator	& end() \\
\hline
QMap::const\_iterator	& end() const \\ 
\hline
QPair<QMap::iterator, QMap::iterator> &	equal\_range(const Key \&key) \\    
\hline
QPair<QMap::const\_iterator, QMap::const\_iterator> &	equal\_range(const Key \&key) const \\
\hline 
QMap::iterator	&erase(QMap::iterator pos) \\ 
\hline
QMap::iterator	&find(const Key \&key) \\
\hline
QMap::const\_iterator	&find(const Key \&key) const \\ 
\hline
T &	first() \\ 
\hline
const T &	first() const \\
\hline
const Key &	firstKey() const \\
\hline
QMap::iterator	&insert(const Key \&key, const T \&value) \\
\hline
QMap::iterator	&insert(QMap::const\_iterator pos, const Key \&key, const T \&value) \\
\hline
void	&insert(const QMap<Key, T> \&map)\\
\hline
bool	&isEmpty() const \\
\hline
const Key & key(const T \&value, const Key \&defaultKey = Key()) const \\
\hline
QMap::key\_iterator&	keyBegin() const\\
\hline
QMap::key\_iterator &	keyEnd() const \\
\hline
QMap::key\_value\_iterator	&keyValueBegin() \\
\hline
QMap::const\_key\_value\_iterator&	keyValueBegin() const \\
\hline
QMap::key\_value\_iterator&	keyValueEnd() \\ 
\hline
QMap::const\_key\_value\_iterator&	keyValueEnd() const \\
\hline
QList&	keys() const \\
\hline
QList	&keys(const T \&value) const \\
\hline
T &	last() \\ 
\hline
const T &	last() const \\ 
\hline
const Key &	lastKey() const \\ 
\hline
QMap::iterator	&lowerBound(const Key \&key) \\ 
\hline
QMap::const\_iterator	&lowerBound(const Key \&key) const \\
\hline
int	&remove(const Key \&key) \\
\hline
int &	size() const \\ 
\hline
void & swap(QMap<Key, T> \&other) \\ 
\hline
T	& take(const Key \&key) \\ 
\hline
std::map<Key, T> &	toStdMap() const \\
\hline
QMap::iterator&	upperBound(const Key \&key) \\ 
\hline
QMap::const\_iterator &	upperBound(const Key \&key) const \\
\hline
const T	& value(const Key \&key, const T \&defaultValue = T()) const \\
\hline
QList	& values() const\\ 
\hline
bool	& operator!=(const QMap<Key, T> \&other) const \\ 
\hline
bool	& operator==(const QMap<Key, T> \&other) const \\ 
\hline
T &	operator[](const Key \&key) \\ 
\hline
const T	 &operator[](const Key \&key) const \\ 
\hline
\end{longtable}

\section{相关非成员函数}

\begin{longtable}[l]{|r|l|}
\hline
返回类型  & 	函数名 \\
\hline
QDataStream &	operator<<(QDataStream \&out, const QMap<Key, T> \&map) \\ 
\hline
QDataStream &	operator>>(QDataStream \&in, QMap<Key, T> \&map) \\  
\hline
\end{longtable}

\section{详细描述}

QMap<Key, T> 是一种 Qt 泛型容器类。
该类存储键值对，可以用相关联的键快速查找值。

QMap 的功能与 QHash 非常相似。二者的区别在于：

\begin{compactitem}
\item QHash 的平均查找速度比 QMap 快。（详情请看算法复杂度。）
\item 遍历 QHash 时，元素的顺序是任意的。而遍历 QMap 时，元素总是按照键的顺序排好序的。
\item QHash 的键类型必须提供 operator==() 运算符和全局的 qHash(Key) 函数。QMap 的键类型必须提供 operator<() 运算符来确定全序。从 Qt5.8.1 起，即使底层的 operator<() 运算符没有提供全序，使用指针作为键类型也是安全的。
\end{compactitem}

下面是一个键类型为 QString，值类型为 int 的 QMap 的示例：

\begin{cppcode}
QMap<QString, int> map;
\end{cppcode}

可以使用 operator[]() 运算符将键值对插入到 map 中：

\begin{cppcode}
map["one"] = 1;
map["three"] = 3;
map["seven"] = 7;
\end{cppcode}


上面的代码将3个键值对插入到 QMap 中：("one", 1)，("three", 3) 和 ("seven", 7)。另外一种向 map 中插入元素的方法是使用 insert()：

\begin{cppcode}
map.insert("twelve", 12);
\end{cppcode}

使用 operator[]() 运算符或 value() 查找值：

\begin{cppcode}
int num1 = map["thirteen"];
int num2 = map.value("thirteen");
\end{cppcode}

如果 map 中不存在指定的键，这些函数返回默认构造的值。

如果想检查 map 中是否包含特定键，使用 contains()：

\begin{cppcode}
int timeout = 30;
if (map.contains("TIMEOUT"))
    timeout = map.value("TIMEOUT");
\end{cppcode}

还有一个 value() 的重载函数，如果 map 中不存在指定键的元素，该函数使用第2个参数作为默认值：


一般推荐使用 contains() 和 value() 而不是 operator[]() 运算符查找 map 中的键。原因是如果 map 中不存在相同键的元素，operator[]() 运算符会默默地将一个元素插入到 map 中（除非 map 是 const 的）。例如，下面的代码片段将在内存中创建1000个元素：

\begin{cppcode}
// 错误
QMap<int, QWidget *> map;
...
for (int i = 0; i < 1000; ++i) {
    if (map[i] == okButton)
        cout << "Found button at index " << i << Qt::endl;
}
\end{cppcode}

为了避免这个问题，将上面代码中的 map[i] 替换为 map.value(i)。

如果想遍历 QMap 中存储的所有键值对，可以使用迭代器。
QMap 同时提供 Java 风格迭代器（QMapIterator 和 QMutableMapIterator）和 STL 风格迭代器（QMap::const\_iterator 和 QMap::iterator）。
下面是使用 Java 风格迭代器遍历 QMap<QString, int> 的方法：

\begin{cppcode}
QMapIterator<QString, int> i(map);
while (i.hasNext()) {
    i.next();
    cout << i.key() << ": " << i.value() << Qt::endl;
}
\end{cppcode}

下面是相同的代码，不过这次使用 STL 风格迭代器：

\begin{cppcode}
QMap<QString, int>::const_iterator i = map.constBegin();
while (i != map.constEnd()) {
    cout << i.key() << ": " << i.value() << Qt::endl;
    ++i;
}
\end{cppcode}

上面的代码按照键的升序遍历各元素。

通常，QMap 每个键只允许有一个值。如果用已经存在的键调用 insert()，先前的值将被删除。例如：

\begin{cppcode}
map.insert("plenty", 100);
map.insert("plenty", 2000);
// map.value("plenty") == 2000
\end{cppcode}

然而，可以使用派生类 QMultiMap 在一个键中存储多个值。使用 values(const Key \&key) 取得单个键关联的所有值，该函数返回一个 QList<T>：

\begin{cppcode}
QList<int> values = map.values("plenty");
for (int i = 0; i < values.size(); ++i)
    cout << values.at(i) << Qt::endl;
\end{cppcode}

共享同一键的多个元素按照从最新到最早插入的顺序返回。
另外一种方法是调用 find() 取得 STL 风格迭代器，该迭代器指向共享同一键的多个元素中的第一个元素，
然后从该元素开始遍历：

\begin{cppcode}
QMap<QString, int>::iterator i = map.find("plenty");
while (i != map.end() && i.key() == "plenty") {
    cout << i.value() << Qt::endl;
    ++i;
}
\end{cppcode}

如果只想从 map 中获取值（而不是键），也可以使用 foreach：

\begin{cppcode}
QMap<QString, int> map;
...
foreach (int value, map)
    cout << value << Qt::endl;
\end{cppcode}

移除元素有几种方法。一种是调用 remove()；
该函数移除指定键的所有元素。
另一种方法是使用 QMutableMapIterator::remove()。
另外，还可以使用 clear() 清除整个 map。

QMap 键和值的数据类型必须是可赋值数据类型。
这涵盖了大多数可能会遇到的数据类型，但是编译器不会存储 QWidget 这样的对象作为值，应该存储 QWidget *。
另外，QMap 的键类型必须提供 operator<() 运算符。
QMap 用它来保持元素有序，并假定两个键 x 和 y 在 x < y 和 y < x 都不为 true 的情况下相等。

例子：

\begin{cppcode}
#ifndef EMPLOYEE_H
#define EMPLOYEE_H

class Employee
{
public:
    Employee() {}
    Employee(const QString &name, QDate dateOfBirth);
    ...

private:
    QString myName;
    QDate myDateOfBirth;
};

inline bool operator<(const Employee &e1, const Employee &e2)
{
    if (e1.name() != e2.name())
        return e1.name() < e2.name();
    return e1.dateOfBirth() < e2.dateOfBirth();
}

#endif // EMPLOYEE_H
\end{cppcode}

该例中，先比较雇员名。如果雇员名相等，再比较二者的生日来分出大小。

\begin{seeAlso}
QMapIterator，QMutableMapIterator，QHash 和 QSet。
\end{seeAlso}

\section{成员类型文档}

typedef QMap::ConstIterator

QMap<Key, T>::const\_iterator 的 Qt 风格的别名。

\splitLine

typedef QMap::Iterator

QMap<Key, T>::iterator 的 Qt 风格的别名。

\splitLine

typedef QMap::const\_key\_value\_iterator

QMap::const\_key\_value\_iterator 类型定义为 QMap 和 QMultiMap 提供 STL 风格迭代器。

除了 operator *() 运算符返回的是键值对而不是值之外，QMap::const\_key\_value\_iterator 基本和 QMap::const\_iterator 相同。

Qt 5.10 中引入该类型定义。

\begin{seeAlso}
QKeyValueIterator。
\end{seeAlso}

\splitLine

typedef QMap::difference\_type

ptrdiff\_t 的类型别名。为兼容 STL 提供。

typedef QMap::key\_type

Key 的类型别名。为兼容 STL 提供。

\splitLine

typedef QMap::key\_value\_iterator
QMap::key\_value\_iterator 类型定义为 QMap 和 QMultiMap 提供 STL 风格迭代器。

除了 operator *() 运算符返回的是键值对而不是值之外，QMap::key\_value\_iterator 基本和 QMap::iterator 相同。

Qt 5.10 中引入该类型定义。

\begin{seeAlso}
QKeyValueIterator。
\end{seeAlso}

\splitLine

typedef QMap::mapped\_type

T 的类型别名。为兼容 STL 提供。

\splitLine

typedef QMap::size\_type

int 的类型别名。为兼容 STL 提供。

\section{成员函数文档}

QMap::QMap(const typename std::map<Key, T> \emph{\&other})

构造一个 \emph{other} 的副本。

\begin{seeAlso}
toStdMap()。
\end{seeAlso}

\splitLine

QMap::QMap(QMap<Key, T> \emph{\&\&other})

移动构造一个 QMap 实例，使该实例指向 \emph{other} 所指向的同一对象。

Qt 5.2 中引入该函数。

\splitLine

QMap::QMap(const QMap<Key, T> \&other)

构造一个 other 的副本。

该操作需要常数时间，因为 QMap 是隐式共享的。这使得从一个函数返回 QMap 非常快。如果共享实例被修改了，它将以线性时间被复制一份（写时拷贝）。

\begin{seeAlso}
operator=()。
\end{seeAlso}

\splitLine

QMap::QMap(std::initializer\_list<std::pair<Key, T>> list)

用初始化列表 list 中每个元素的副本构造一个 map。

只有当程序在 C++11 模式下编译时，该函数才可用。

Qt 5.1 中引入该函数。

\splitLine

QMap::QMap()

构造一个空 map。
 
\begin{seeAlso}
clear()。
\end{seeAlso}
	
\splitLine

QMap<Key, T> \&QMap::operator=(QMap<Key, T> \emph{\&\&other})

移动赋值 \emph{other} 到该 QMap 实例。

Qt 5.2 中引入该函数。

\splitLine

QMap<Key, T> \&QMap::operator=(const QMap<Key, T> \emph{\&other})

将 \emph{other} 赋值给该 map 并返回该 map 的引用。

QMap::$\sim$QMap()

析构 map。该 map 中值的引用及所有该 map 的迭代器都将失效。

\splitLine

QMap::iterator QMap::begin()

返回 STL 风格迭代器，指向 map 中的第一个元素。

\begin{seeAlso}
constBegin() 和 end()。
\end{seeAlso}

\splitLine

QMap::const\_iterator QMap::begin() const

这是一个重载函数。

\splitLine

QMap::const\_iterator QMap::cbegin() const

返回常量类型的 STL 风格迭代器，指向 map 中的第一个元素。

Qt 5.0 中引入该函数。

\begin{seeAlso}
begin() 和 cend()。
\end{seeAlso}

\splitLine

QMap::const\_iterator QMap::cend() const

返回常量类型的 STL 风格迭代器，指向 map 中最后一个元素之后的假想元素。

Qt 5.0 中引入该函数。

\begin{seeAlso}
cbegin() 和 end()。
\end{seeAlso}

\splitLine

void QMap::clear()

从 map 中移除所有元素。

\begin{seeAlso}
remove()。
\end{seeAlso}

\splitLine

QMap::const\_iterator QMap::constBegin() const

返回常量类型的 STL 风格迭代器，指向 map 中的第一个元素。

\begin{seeAlso}
begin() 和 constEnd()。
\end{seeAlso}

\splitLine

QMap::const\_iterator QMap::constEnd() const

返回常量类型的 STL 风格迭代器，指向 map 中最后一个元素之后的假想元素。

\begin{seeAlso}
constBegin() 和 end()。
\end{seeAlso}

\splitLine

QMap::const\_iterator QMap::constFind(const Key \emph{\&key}) const

返回常量类型的迭代器，指向 map 中键为 key 的元素。

如果 map 不包含键为 key 的元素，该函数返回 constEnd()。

Qt 4.1 中引入该函数。

\begin{seeAlso}
find() 和 QMultiMap::constFind()。
\end{seeAlso}

\splitLine

QMap::const\_key\_value\_iterator QMap::constKeyValueBegin() const

返回常量类型的 STL 风格迭代器，指向 map 中的第一项.

Qt 5.10 中引入该函数。

\begin{seeAlso}
keyValueBegin()。
\end{seeAlso}

\splitLine

QMap::const\_key\_value\_iterator QMap::constKeyValueEnd() const

返回常量类型的 STL 风格迭代器，指向 map 中最后一项之后的假想项。

Qt 5.10 中引入该函数。

\begin{seeAlso}
constKeyValueBegin()。
\end{seeAlso}

\splitLine

bool QMap::contains(const Key \emph{\&key}) const

如果该 map 包含键为 \emph{key} 的元素，返回 true；否则返回 false。

\begin{seeAlso}
count() 和 QMultiMap::contains()。
\end{seeAlso}

\splitLine

int QMap::count(const Key \emph{\&key}) const

返回与键 \emph{key} 相关联的元素个数。

\begin{seeAlso}
contains() 和 QMultiMap::count()。
\end{seeAlso}

\splitLine

int QMap::count() const

这是一个重载函数。

同 size().

\splitLine

bool QMap::empty() const

该函数为兼容 STL 提供。与 isEmpty() 等价，
如果 map 为空，返回 true；否则返回 false。

\splitLine

QMap::iterator QMap::end()

返回 STL 风格迭代器，指向 map 中最后一个元素之后的假想元素。

\begin{seeAlso}
begin() 和 constEnd()。
\end{seeAlso}

\splitLine

QMap::const\_iterator QMap::end() const

这是一个重载函数。

\splitLine

QPair<QMap::iterator, QMap::iterator> QMap::equal\_range(const Key \emph{\&key})

返回一对迭代器界定与 key 相关联的值的范围 [first, second)。

\splitLine

QPair<QMap::const\_iterator, QMap::const\_iterator> QMap::equal\_range(const Key \&key) const

这是一个重载函数。

Qt 5.6 中引入该函数。

\splitLine

QMap::iterator QMap::erase(QMap::iterator \emph{pos})

从 map 中移除迭代器 \emph{pos} 指向的键值对，返回指向 map 中下一个元素的迭代器。


\begin{seeAlso}
remove()。
\end{seeAlso}

\splitLine

QMap::iterator QMap::find(const Key \emph{\&key})

返回迭代器，指向 map 中键为 key 的元素。

如果 map 不包含键为 key 的元素，函数返回 end()。

如果 map 包含多个键为 key 的元素，函数返回指向最新插入的那个值的迭代器。
其它值可以通过递增迭代器取得。

例如，下面的代码遍历同一键的所有元素：

\begin{cppcode}
QMap<QString, int> map;
...
QMap<QString, int>::const_iterator i = map.find("HDR");
while (i != map.end() && i.key() == "HDR") {
    cout << i.value() << Qt::endl;
    ++i;
}
\end{cppcode}

\begin{seeAlso}
constFind()，value()，values()，lowerBound()，upperBound() 和 QMultiMap::find()。
\end{seeAlso}

\splitLine

QMap::const\_iterator QMap::find(const Key \&key) const

这是一个重载函数。

\splitLine

T \&QMap::first()

返回指向 map 中第一个值的引用，即映射到最小键的值。该函数假定 map 不为空。

对于非共享 map（或者调用的是常量版本），该函数在常数时间内完成。

Qt 5.2 中引入该函数。


\begin{seeAlso}
last()，firstKey() 和 isEmpty()。
\end{seeAlso}

\splitLine

const T \&QMap::first() const

这是一个重载函数。

Qt 5.2 中引入该函数。

\splitLine

const Key \&QMap::firstKey() const

返回 map 中最小键的引用。该函数假定 map 不为空。

该操作在常数时间内完成。

Qt 5.2 中引入该函数。


\begin{seeAlso}
lastKey()，first()，keyBegin() 和 isEmpty()。
\end{seeAlso}

\splitLine

QMap::iterator QMap::insert(const Key \emph{\&key}, const T \emph{\&value})

用键 \emph{key} 和值 \emph{value} 插入一个新元素。

如果已经存在键为 \emph{key} 的元素，该元素的值将被 \emph{value} 替换。

如果有多个键为 \emph{key} 的元素，最新插入的元素的值将被 \emph{value} 替换。

\begin{seeAlso}
QMultiMap::insert()。
\end{seeAlso}

\splitLine

QMap::iterator QMap::insert(QMap::const\_iterator \emph{pos}, const Key \emph{\&key}, const T \emph{\&value})

这是一个重载函数。

用键 key 和值 value 插入一个新元素，pos 用来提示插入位置。

如果以 constBegin() 作为插入位置提示，表明 key 比 map 中的任何键都小，
而 constEnd() 则建议 key（严格）大于 map 中的任何键。
否则提示应该满足条件 (pos - 1).key() < key <= pos.key()。
如果提示 pos 是错误的，其将被忽略，并以常规方式插入。

如果已经存在键为 key 的元素，该元素的值将被 value 替换。

如果有多个键为 key 的元素，只会有一个元素的值被 value 替换。

如果提示是正确的，并且 map 未被共享，插入操作平均在常数时间内完成。

从有序数据创建 map 时，从最大键的元素开始以 constBegin() 作为提示插入，
比按从小到大的顺序以 constEnd() 作为提示插入更快，因为 constEnd() - 1 （用来检查提示是否合法）需要对数时间。

\begin{notice}
需小心对待提示。提供从旧的共享实例取得的迭代器可能引起崩溃，还会有默默污染 map 和 pos 的 map 的风险。
\end{notice}

Qt 5.1 中引入该函数。

\begin{seeAlso}
QMultiMap::insert()。
\end{seeAlso}

\splitLine

void QMap::insert(const QMap<Key, T> \emph{\&map})

将 map 中的所有元素插入到本 \emph{map} 中。

如果一个键同时在两个 \emph{map} 中出现，其值将被传入的 \emph{map} 中存储的值替换。

\begin{seeAlso}
如果传入的 map 中同一键关联多个元素，则该键的最终值未定义。
\end{seeAlso}

Qt 5.15 中引入该函数。

\begin{seeAlso}
QMultiMap::insert()。
\end{seeAlso}

\splitLine

bool QMap::isEmpty() const

如果 map 中不包含元素，返回 true；否则返回 false。

\begin{notice}
size()。
\end{notice}

\splitLine

const Key QMap::key(const T \emph{\&value}, const Key \&defaultKey = Key()) const

这是一个重载函数。

返回与值 \emph{value} 对应的第一个键，如果 map 不包含值为 value 的元素，返回 defaultKey。如果没有提供 defaultKey，函数返回默认构造的键。

该函数可能会比较慢（线性时间），因为 QMap 的内部数据结构是以快速查找键而不是值为目标来优化的。

Qt 4.3 中引入该函数。

\begin{seeAlso}
value() 和 keys()。
\end{seeAlso}

\splitLine

QMap::key\_iterator QMap::keyBegin() const

返回常量类型的 STL 风格迭代器，指向 map 中的第一个键。

Qt 5.6 中引入该函数。

\begin{seeAlso}
keyEnd() 和 firstKey()。
\end{seeAlso}

\splitLine

QMap::key\_iterator QMap::keyEnd() const

返回常量类型的 STL 风格迭代器，指向 map 中的最后一个元素之后的假想元素的键。

Qt 5.6 中引入该函数。

\begin{seeAlso}
keyBegin() 和 lastKey()。
\end{seeAlso}

\splitLine

QMap::key\_value\_iterator QMap::keyValueBegin()

返回 STL 风格迭代器，指向 map 中的第一项。

Qt 5.10 中引入该函数。

\begin{seeAlso}
keyValueEnd().
\end{seeAlso}

\splitLine

QMap::const\_key\_value\_iterator QMap::keyValueBegin() const

返回常量类型的 STL 风格迭代器，指向 map 中的第一项。

Qt 5.10 中引入该函数。

\begin{seeAlso}
keyValueEnd()。
\end{seeAlso}

\splitLine

QMap::key\_value\_iterator QMap::keyValueEnd()

返回 STL 风格迭代器，指向 map 中最后一项之后的假想项。

Qt 5.10 中引入该函数。

\begin{seeAlso}
keyValueBegin()。
\end{seeAlso}

\splitLine

QMap::const\_key\_value\_iterator QMap::keyValueEnd() const

返回常量类型的 STL 风格迭代器，指向 map 中最后一项之后的假想项。

Qt 5.10 中引入该函数。

\begin{seeAlso}
keyValueBegin()。
\end{seeAlso}

\splitLine

QList<Key> QMap::keys() const

以升序返回 map 中所有键的列表。在 map 中多次出现的键（当该方法应用在 QMultiMap 时）也会在列表中多次出现。

键的顺序将确保与通过 values() 返回的值的顺序相同。

\begin{seeAlso}
QMultiMap::uniqueKeys()，values() 和 key()。
\end{seeAlso}

\splitLine

QList<Key> QMap::keys(const T \emph{\&value}) const

这是一个重载函数。

以升序返回所有与值 \emph{value} 相关联的键的列表。

该函数可能会比较慢（线性时间），因为 QMap 的内部数据结构是以快速查找键而不是值为目标来优化的。

\splitLine

T \&QMap::last()

返回 map 中最后一个值的引用，即映射到最大键的值。该函数假定 map 不为空。

对于非共享 map（或者调用的是常量版本)，该函数在对数时间内完成。

Qt 5.2 中引入该函数。

\begin{seeAlso}
first()，lastKey() 和 isEmpty()。
\end{seeAlso}

\splitLine

const T \&QMap::last() const

这是一个重载函数。

Qt 5.2 中引入该函数。

\splitLine

const Key \&QMap::lastKey() const

返回 map 中最大键的引用。该函数假定 map 不为空。

该函数在对数时间内完成。

Qt 5.2 中引入该函数。

\begin{seeAlso}
firstKey()，last()，keyEnd() 和 isEmpty()。
\end{seeAlso}

\splitLine

QMap::iterator QMap::lowerBound(const Key \emph{\&key})

返回指向 map 中键 \emph{key} 所关联的第一个元素的迭代器。如果 map 不包含键为 key 的元素，函数返回指向距离下一个键最近的元素的迭代器。

例子：

\begin{cppcode}
QMap<int, QString> map;
map.insert(1, "one");
map.insert(5, "five");
map.insert(10, "ten");

map.lowerBound(0);      // 返回指向 (1, "one") 的迭代器
map.lowerBound(1);      // 返回指向 (1, "one") 的迭代器
map.lowerBound(2);      // 返回指向 (5, "five") 的迭代器
map.lowerBound(10);     // 返回指向 (10, "ten") 的迭代器
map.lowerBound(999);    // 返回 end()
\end{cppcode}

如果 map 包含多个键为 key 的元素，该函数返回指向最新插入的值的迭代器。其它值可以通过递增迭代器访问。例如，下面的例子遍历同一键所关联的所有元素：

\begin{cppcode}
QMap<QString, int> map;
...
QMap<QString, int>::const_iterator i = map.lowerBound("HDR");
QMap<QString, int>::const_iterator upperBound = map.upperBound("HDR");
while (i != upperBound) {
    cout << i.value() << Qt::endl;
    ++i;
}
\end{cppcode}

%%%%%%%%%
\begin{seeAlso}
upperBound() 和 find()。
\end{seeAlso}
    

QMap::const\_iterator QMap::lowerBound(const Key \emph{\&key}) const

这是一个重载函数。

\splitLine

int QMap::remove(const Key \emph{\&key})

从 map 中移除所有键为 \emph{key} 的元素。返回被移除的元素个数，如果键存在，则为1，否则为0。

\begin{seeAlso}
clear()，take() 和 QMultiMap::remove()。
\end{seeAlso}

\splitLine

int QMap::size() const

返回 map 中键值对的个数。

\begin{seeAlso}
isEmpty() 和 count()。
\end{seeAlso}
    

\splitLine

void QMap::swap(QMap<Key, T> \emph{\&other})

将 map other 与本 map 交换。该操作非常快，永远不失败。

Qt 4.8 中引入该函数。

\splitLine

T QMap::take(const Key \emph{\&key})

从 map 中移除键为 \emph{key} 的元素，返回键 \emph{key} 所关联的值。

如果 map 中不存在该元素，该函数简单返回一个默认构造的值。如果 map 中有多个键为 key 的元素，只移除最新插入的元素并返回值。

如果不使用返回值，使用 remove() 更高效一些。

\begin{seeAlso}
remove()。
\end{seeAlso}

\splitLine

std::map<Key, T> QMap::toStdMap() const

返回与这个 QMap 相对应的 STL map。

\splitLine

QMap::iterator QMap::upperBound(const Key \emph{\&key})

返回迭代器，指向 map 中首个大于键 \emph{key} 的元素。如果 map 不包含键为 \emph{key} 的元素，该函数返回指向距离下一个键最近的元素的迭代器。

例子：

\begin{cppcode}
QMap<int, QString> map;
map.insert(1, "one");
map.insert(5, "five");
map.insert(10, "ten");

map.upperBound(0);      // 返回指向 (1, "one") 的迭代器
map.upperBound(1);      // 返回指向 (5, "five") 的迭代器
map.upperBound(2);      // 返回指向 (5, "five") 的迭代器
map.upperBound(10);     // 返回 end()
map.upperBound(999);    // 返回 end()
\end{cppcode}

%%%%%%
\begin{seeAlso}
lowerBound() 和 find()。
\end{seeAlso}

QMap::const\_iterator QMap::upperBound(const Key \emph{\&key}) const

这是一个重载函数。

\splitLine

const T QMap::value(const Key \emph{\&key}, const T \&defaultValue = T()) const

返回键 key 关联的值。

如果 map 不包含键为 \emph{key} 的元素，该函数返回 defaultValue。 如果没有指定 defaultValue，该函数返回默认构造的值。如果 map 中有多个键为 key 的元素，返回最新插入的元素的值。

\begin{seeAlso}
key()，values()，contains() 和 operator[]()。
\end{seeAlso}

\splitLine

QList<T> QMap::values() const

按照键升序返回 map 中所有值的列表。如果一个键关联到多个值，该键的所有值都将被放入列表中，而不只是最新插入的值。

\begin{seeAlso}
keys() 和 value()。
\end{seeAlso}

\splitLine

bool QMap::operator!=(const QMap<Key, T> \emph{\&other}) const

如果 other 与本 map 不相等，返回 true，否则返回 false。

如果两个 map 包含相同的键值对，则认为二者相等。

该函数需要值类型实现 operator==()。

\begin{seeAlso}
operator==()。
\end{seeAlso}

\splitLine

bool QMap::operator==(const QMap<Key, T> \emph{\&other}) const

如果 \emph{other} 与本 map 相等，返回 true，否则返回 false。

如果两个 map 包含相同的键值对，则认为二者相等。

该函数需要值类型实现 operator==()。

\begin{seeAlso}
operator!=()。
\end{seeAlso}

\splitLine

T \&QMap::operator[](const Key \emph{\&key})

返回键 \emph{key} 所关联的值的可修改引用。

如果 map 不包含键为 \emph{key} 的元素，该函数用键 \emph{key} 插入一个默认构造的值，并返回该值的引用。
如果 map 包含多个键为  \emph{key} 的元素，该函数返回最新插入的那个值的引用。

\begin{seeAlso}
insert() 和 value()。
\end{seeAlso}

\splitLine

const T QMap::operator[](const Key \emph{\&key}) const

这是一个重载函数。

同 value()。

\section{相关非成员函数}

template <typename Key, typename T> QDataStream \&operator<<(QDataStream \emph{\&out}, const QMap<Key, T> \emph{\&map})

将 \emph{map} 写出到流 \emph{out}。

该函数需要键和值类型实现 operator<<()。

\begin{seeAlso}
QDataStream 运算符的格式。
\end{seeAlso}

\splitLine

template <typename Key, typename T> QDataStream \&operator>>(QDataStream \emph{\&in}, QMap<Key, T> \emph{\&map})

从流 in 读入数据到 map。

该函数需要键和值类型实现 operator>>()。

\begin{seeAlso}
QDataStream 运算符的格式。
\end{seeAlso}